6.9 --output-format - 指定输出格式

概述#

--output-format 标志允许您指定 Claude 响应的输出格式。这对于自动化脚本、数据处理、API 集成等场景非常有用。

基本语法#

bash
复制
claude --output-format <格式>

支持的格式#

使用场景#

1. JSON 格式输出#

用于自动化脚本和数据处理：

bash
复制
# 获取 JSON 格式的响应
claude --output-format json -p "分析这个 Python 文件的结构"

# 输出示例
{
  "analysis": {
    "language": "Python",
    "functions": ["main", "process_data", "calculate"],
    "imports": ["os", "sys", "json"],
    "complexity": "medium"
  },
  "suggestions": [
    "添加类型注解",
    "拆分长函数",
    "添加错误处理"
  ]
}

2. Markdown 格式输出#

用于文档生成和技术写作：

bash
复制
# 生成 Markdown 格式的文档
claude --output-format markdown -p "为这个 API 生成文档"

# 输出示例
# API 文档
## 用户认证
### POST /api/auth/login
登录用户账号。
```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "username": "john_doe"
  }
}
```

3. YAML 格式输出#

用于配置文件生成：

bash
复制
# 生成 YAML 格式的配置
claude --output-format yaml -p "生成一个 Docker Compose 配置"

# 输出示例
version: '3.8'
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html
  db:
    image: postgres:13
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - postgres_data:/var/lib/postgresql/data
volumes:
  postgres_data:

4. 纯文本格式输出#

用于一般对话和代码生成：

bash
复制
# 默认文本格式
claude --output-format text -p "解释什么是递归"

# 输出示例
递归是一种编程技术，函数直接或间接地调用自身。

基本原理：
1. 基础情况：递归的终止条件
2. 递归情况：函数调用自身，但参数更接近基础情况

示例：
def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)

高级用法#

1. 与其他标志组合#

bash
复制
# JSON 格式 + 指定模型
claude --output-format json --model opus -p "分析代码"

# Markdown 格式 + 限制工具
claude --output-format markdown --allowedTools "Read" "Grep" -p "生成文档"

# YAML 格式 + 详细日志
claude --output-format yaml --verbose -p "生成配置"

2. 管道输出到文件#

bash
复制
# 将 JSON 输出保存到文件
claude --output-format json -p "分析项目结构" > analysis.json

# 将 Markdown 输出保存到文件
claude --output-format markdown -p "生成 README" > README.md

# 将 YAML 输出保存到文件
claude --output-format yaml -p "生成配置" > config.yaml

3. 与其他工具集成#

bash
复制
# 使用 jq 处理 JSON 输出
claude --output-format json -p "获取文件列表" | jq '.files[]'

# 使用 pandoc 转换 Markdown
claude --output-format markdown -p "生成文档" | pandoc -o doc.pdf

# 使用 yq 处理 YAML 输出
claude --output-format yaml -p "生成配置" | yq '.services[].image'

4. 在脚本中使用#

bash
复制
#!/bin/bash
# analyze.sh

# 获取 JSON 格式的分析结果
RESULT=$(claude --output-format json -p "分析代码质量")

# 提取评分
SCORE=$(echo "$RESULT" | jq '.score')

# 根据评分执行不同操作
if [ "$SCORE" -gt 80 ]; then
    echo "代码质量优秀"
else
    echo "代码质量需要改进"
fi

实际应用示例#

示例 1: 自动化代码审查#

bash
复制
#!/bin/bash
# code-review.sh
FILE=$1

# 获取 JSON 格式的审查结果
REVIEW=$(claude --output-format json \
--append-system-prompt "代码审查重点：安全性、性能、可维护性" \
-p "审查 $FILE 的代码质量")

# 提取问题数量
ISSUES=$(echo "$REVIEW" | jq '.issues | length')
echo "发现 $ISSUES 个问题"

# 如果有问题，显示详细信息
if [ "$ISSUES" -gt 0 ]; then
echo "$REVIEW" | jq '.issues[]'
fi

示例 2: 自动生成文档#

bash
复制
#!/bin/bash
# generate-docs.sh

# 为所有 Python 文件生成 Markdown 文档
for file in src/*.py; do
    echo "为 $file 生成文档..."

    claude --output-format markdown \
      --append-system-prompt "生成符合 Google 风格的 API 文档" \
      -p "为 $file 生成文档" > "docs/$(basename $file .py).md"
done

echo "文档生成完成"

示例 3: 配置文件生成#

bash
复制
#!/bin/bash
# generate-config.sh

# 生成 YAML 格式的配置文件
claude --output-format yaml \
--append-system-prompt "生成生产环境的配置文件" \
-p "生成包含 Web 服务器、数据库和缓存的配置" > docker-compose.yml

echo "配置文件已生成：docker-compose.yml"

示例 4: 数据分析报告#

bash
复制
#!/bin/bash
# analyze-data.sh

DATA_FILE=$1

# 获取 JSON 格式的分析结果
ANALYSIS=$(claude --output-format json \
  --append-system-prompt "数据分析重点：趋势、异常、建议" \
  -p "分析 $DATA_FILE 中的数据")

# 生成 Markdown 报告
cat > report.md << EOF
# 数据分析报告

## 概述
\$(echo "$ANALYSIS" | jq -r '.summary')

## 关键指标
\$(echo "$ANALYSIS" | jq -r '.metrics | to_entries[] | "- \(.key): \(.value)"')

## 建议
\$(echo "$ANALYSIS" | jq -r '.recommendations[] | "- \(.)"')
EOF

echo "报告已生成：report.md"

格式特定技巧#

JSON 格式技巧#

bash
复制
# 请求结构化的 JSON 输出
claude --output-format json -p "以 JSON 格式返回文件列表，包含文件名、大小和修改时间"

# 在提示中指定 JSON 结构
claude --output-format json -p "返回以下 JSON 结构：{\"files\": [{\"name\": \"\", \"size\": 0, \"lines\": 0}]}"

# 使用 jq 提取特定字段
claude --output-format json -p "分析代码" | jq '.suggestions[]'

Markdown 格式技巧#

bash
复制
# 请求特定类型的 Markdown 内容
claude --output-format markdown -p "生成包含代码示例和表格的 Markdown 文档"

# 生成 API 文档
claude --output-format markdown -p "生成 OpenAPI 规范格式的 API 文档"

# 生成技术博客
claude --output-format markdown -p "写一篇关于微服务架构的技术博客"

YAML 格式技巧#

bash
复制
# 生成 Kubernetes 配置
claude --output-format yaml -p "生成 Kubernetes Deployment 和 Service 配置"

# 生成 CI/CD 配置
claude --output-format yaml -p "生成 GitHub Actions 工作流配置"

# 生成多环境配置
claude --output-format yaml -p "生成开发、测试和生产环境的配置"

最佳实践#

1. 选择合适的格式#

bash
复制
# 数据处理和自动化 -> JSON
claude --output-format json -p "分析数据"

# 文档和技术写作 -> Markdown
claude --output-format markdown -p "生成文档"

# 配置文件 -> YAML
claude --output-format yaml -p "生成配置"

# 一般对话 -> text（默认）
claude -p "解释概念"

2. 在提示中指定结构#

bash
复制
# 明确指定 JSON 结构
claude --output-format json -p "返回 JSON：{\"result\": \"\", \"confidence\": 0.0}"

# 明确指定 Markdown 结构
claude --output-format markdown -p "生成包含标题、代码块和表格的 Markdown"

3. 验证输出格式#

bash
复制
# 验证 JSON 格式
claude --output-format json -p "分析代码" | jq . > /dev/null && echo "JSON 有效"

# 验证 YAML 格式
claude --output-format yaml -p "生成配置" | yq eval . > /dev/null && echo "YAML 有效"

4. 错误处理#

bash
复制
#!/bin/bash
# 处理 JSON 输出错误
RESULT=$(claude --output-format json -p "分析代码")
if ! echo "$RESULT" | jq . > /dev/null 2>&1; then
echo "错误：无效的 JSON 输出"
echo "$RESULT"
exit 1
fi
echo "JSON 输出有效"

常见问题#

Q1: 所有格式都支持吗？#

A: 支持的格式包括 text、json、markdown 和 yaml。某些复杂格式可能需要额外的处理。

Q2: 如何确保输出是有效的格式？#

A: 可以使用相应的验证工具（如 jq 验证 JSON，yq 验证 YAML）来验证输出。

Q3: 可以自定义输出格式吗？#

A: 不可以直接自定义格式，但可以在提示中指定输出的结构和内容。

Q4: JSON 输出的大小有限制吗？#

A: 有一定的限制，但对于大多数应用场景来说足够。如果输出很大，考虑分批处理。

Q5: 如何处理格式错误？#

A: 使用验证工具检查输出，并在脚本中添加错误处理逻辑。

与其他工具的集成#

1. 与 jq 集成#

bash
复制
# 提取特定字段
claude --output-format json -p "分析代码" | jq '.score'

# 过滤数据
claude --output-format json -p "获取文件列表" | jq '.files[] | select(.size > 1024)'

# 转换格式
claude --output-format json -p "分析数据" | jq -r '.summary'

2. 与 yq 集成#

bash
复制
# 提取配置值
claude --output-format yaml -p "生成配置" | yq '.services.web.image'

# 更新配置
claude --output-format yaml -p "生成配置" | yq '.services.web.ports[0] = "8080:80"' > new-config.yaml

3. 与 pandoc 集成#

bash
复制
# Markdown 转 PDF
claude --output-format markdown -p "生成文档" | pandoc -o document.pdf

# Markdown 转 HTML
claude --output-format markdown -p "生成文档" | pandoc -o document.html

4. 与 Python 集成#

python
复制
import subprocess
import json

# 获取 JSON 输出
result = subprocess.run(
    ['claude', '--output-format', 'json', '-p', '分析代码'],
    capture_output=True,
    text=True
)

# 解析 JSON
data = json.loads(result.stdout)

# 使用数据
print(f"分数: {data['score']}")
print(f"建议: {data['suggestions']}")